This Technote provides an example of creating an off-screen bitmap by hand, drawing to it, and then copying from it to the screen. Apple encourages the use of GWorlds for your off-screen needs. In some cases, however, creating your own off-screens can be beneficial. The resulting off-screen bitmaps can be used like a 1-bit GWorld, but with improved performance.
This technique is useful for the creation of regions when OpenRgn is not an option. For example, in making a region from a line, draw the line in an offscreen and call BitMapToRegion to convert the off-screen's bitmap to a region. These off-screen bitmaps can be also be substituted for pixmaps in routines such as CopyMask, where the mask is black and white, and s ªpeed is of great importance.
This Technote is written primarily for those involved in speed-critical projects, such as game developers and graphics applications developers.
Note: This technique for creating off-screen bitmaps is intended for black and white uses only. If your needs include only color ports, you should review the Technote ÒTechniques for Creating Off-Screen Graphics Environments.Ó
Drawing Off-Screen Bitmaps
The following is an example of creating and drawing to an off-screen bitmap, then copying from it to an on-screen window. The example is supplied in both a C and Pascal versions, and will work with all compilers.
Creating an Off-Screen Bitmap in C
LetÕs look at a general purpose function to create an off-screen bitmap. This function creates the GrafPort on the heap. You can also create it on the stack and pass the uninitialized structure to a function similar to this one.
Boolean CreateOffscreenBitMap( úGrafPtr *newOffscreen, Rect *inBounds)
{
GrafPtr savePort;
GrafPtr newPort;
GetPort(&savePort); /* need this to restore thePort after
OpenPort */
newPort = (GrafPtr) NewPtr(sizeof(GrafPort)); /* allocate the
grafPort */
if (MemError() != noErr)
return false; /* failed to allocate the off-screen
port */
/*
the call to OpenPort does the following . . .
allocates space for visRgn (set to screenBits.bounds) and
clipRgn (set wide open)
sets portBits to screenBits
sets portRect to screenBits.bounds
(See Inside Mac: Imaging with QuickDraw,
pages 2-38 to 2-39)
side effect: does a SetPort(&offScreen)
*/
OpenPort(newPort);
/* make bitmap the size of the bounds that caller supplied */
if (newPort->portBits.baseAddr == nil) { /* check to see if we had enough room for
the bits */
SetPort(savePort);
ClosePort(newPort); /* dump the visRgn and clipRgn */
DisposPtr((Ptr)newPort); /* dump the GrafPort */
return false; /* tell caller we failed */
}
/* since the bits are just memory, let's clear them before we start*/
EraseRect(inBounds); /* OpenPort did a SetPort(newPort) so we
are ok */
*newOffscreen = newPort;
SetPort(savePort);
›return true; /* tell caller we succeeded! */
}
Eliminating an Off-Screen Bitmap in C
To eliminate an off-screen bitmap created by the previous function, use this function:
void DestroyOffscreenBitMap(GrafPtr oldOffscreen)
{
ClosePort(oldOffscreen); /* dump the visRgn and
clipRgn */
DisposPtr(oldOffscreen->portBits.baseAddr); /* dump the bits */
DisposPtr((Ptr)oldOffscreen); /* dump the port */
}
Using an Off-Screen Bitmap in C
Now that you know how to create and destroy an off-screen bitmap, letÕs go through the motions of using one. First, letÕs define a few things to make the NewWindow call a little clearer.
#define kIsVisible true
#define kNoGoAway false
#define kNoWindowStorage 0L
#define kFrontWindow ((WindowPtr) -1L)
HereÕs the body of the test code:
main()
{
char* myString = "\pThe EYE"; /* string to display */
GrafPtr offscreen; /* our off-screen bitmap */
Rect ovalRect; /* used for example ódrawing */
Rect myWBounds; /* for creating window */
Rect OSRect; /* portRect and bounds for off-screen
bitmap*/
WindowPtr myWindow;
InitToolbox(); /* exercise for the reader */
myWBounds = qd.screenBits.bounds; /* size of main screen */
InsetRect(&myWBounds, 50,50); /* make it fit better */
DestroyOffscreenBitMap(offscreen); /* dump the off-screen bitmap*/
while (!Button()); /* give user a chance to see our work of art*/
}
Creating an Off-Screen Bitmap in Pascal
LetÕs look at a general purpose function to create an off-screen bitmap. This function creates the GrafPort on the heap. You can also create it on the stack and pass the uninitialized structure to a function similar to this one. ö
FUNCTION CreateOffscreenBitMap(VAR newOffscreen:GrafPtr; inBounds:Rect)
: BOOLEAN;
savePort : GrafPtr;
newPort : GrafPtr;
GetPort(savePort); {need this to restore thePort after OpenPort
changes it}
newPort := GrafPtr(NewPtr(sizeof(GrafPort))); {allocate the
GrafPort}
IF MemError <> noErr THEN BEGIN
CreateOffscreenBitMap := false; {failed to allocate it}
EXIT(CreateOffscreenBitMap);
END;
{
the OpenPort call does the following . . .
allocates space for visRgn (set to screenBits.bounds) and clipRgn
(set wide open)
sets portBits to screenBits
sets portRect to screenBits.bounds
(See Inside Mac: Imaging with QuickDraw, pages 2-38 to 2-39)
side effect: does a SetPort(offScreen)
}
OpenPort(newPort);
{make bitmap exactly the size of the bounds that caller supplied}
WITH newPort^ DO BEGIN {portRect, clipRgn, and visRgn are in newPort}
portRect := inBounds;
RectRgn(clipRgn, inBounds); {avoid wide-open clipRgn, to be safe}
‡RectRgn(visRgn, inBounds); {in case inBounds is > screen bounds}
END;
WITH newPort^.portBits DO BEGIN {baseAddr, rowBytes and bounds
are in newPort}
bounds := inBounds;
{rowBytes is size of row It must be rounded up to even number
DisposPtr(oldOffscreen^.portBits.baseAddr); {dump the bits }
DisposPtr(Ptr(oldOffscreen)); {dump the port };
Using an Off-Screen Bitmap: MPW Pascal
Now that you know how to create and destroy an off-screen bitmap, letÕs test one out. First, letÕs define a few things to make the NewWindow call a little clearer.
CONST
kIsVisible = true;
kNoGoAway = false;
kMakeFrontWindow = -1;
myString = 'The EYE'; {string to display}
HereÕs the body of the test code:
VAR
offscreen : GrafPtr; {our off-screen bitmap}
ovalRect : Rect; {used for example drawing}
myWBounds : Rect; ≤ {for creating window}
OSRect : Rect; {portRect and bounds for off-screen bitmap}
myWindow : WindowPtr;
InitToolbox; {exercise left to the reader}
myWBounds := screenBits.bounds; {size of main screen }
InsetRect(myWBounds, 50,50); {make it fit better }
DestroyOffscre qenBitMap(offscreen); {remove the evidence}
WHILE NOT Button DO; {give user a chance to see the
results}.
Summary
In the example code, the bits of the BitMap structure pointed to by the baseAddr field are allocated by a NewPtr call.
Keeping a large off-screen around for any length of time may lead to heap fragmentation. One alternative that lessens this problem is to get the bits via NewHandle, so that the Memory Manager can move them when necessary. To implement this approach, you need to keep the handle separate from the GrafPort (for example, in a structure that combines a GrafPort and a Handle). When using the off-screen bitmap, lock the handle and put the dereferenced handle into the baseAddr field. You can then unlock the handle when not using the off-screen bitmap.
Further Reference
¥ Inside Macintosh: Imaging with QuickDraw
Z ÿÿ N ° DSET ≠ ÿÿ . H = X ÿÿÿÿÿÿ≥f ° √ b ¯ È ° ÿÿ 6 ÿÿ * b ¯ DSET Δ ÿÿ . H H H ÿÿÿÿÿÿ≥ex ¯ O ° ÿÿ √ ◊ ° ÿÿ _ ° ÿÿ ˘ ç ° ÿÿ
o ° ÿÿ ¨ ÷ ° ÿÿ 0 ° ÿÿ ¸ ° ÿÿ @ ∂ ° ÿÿ P √ ° ÿÿ Ø ° ÿÿ ` ˘ ° ÿÿ è
° ÿÿ p ¨ ° ÿÿ ø 0 ° ÿÿ • ¸ ° ÿÿ @ ° ÿÿ Δ È ° ÿÿ 6 ÿÿ * b ¯ DSET ≠ ÿÿ . H ÿÿÿÿÿÿ≥eü ?• I 8 ° ÿÿ °
ÿÿ 6 D /0 % ' ÿÿ 7 E 00 % ' ÿÿÿÿ F 10 % & ÿÿÿÿ G 30 % & ÿÿÿÿ H 40 % ( ÿÿ ; I 50 % ( ÿÿÿÿ % J 6‹ ÿÿÿÿ ÿÿ K 70 6 6 ÿÿÿÿ L 80 6 6 ! ÿÿÿÿ M 90 6 6 ! ÿÿÿÿ N ;0 6 8 " ÿÿÿÿ O <0 6 8 # ÿÿÿÿ P =0 6 8 # ÿÿÿÿ Q ?0 6 8 #
ÿÿÿÿ R @0 6 8 # ÿÿÿÿ S A0 6 8 # ÿÿÿÿ T B0 6 7 $ ÿÿÿÿ U C0 6 7 $ ÿÿÿÿ V E0 6 9 " ÿÿÿÿ W F0 6 9 # ÿÿÿÿ % X G‹ ÿÿÿÿ ÿÿ Y H0 G G % ÿÿÿÿ Z I0 G G ÿÿÿÿ [ J0 G G ÿÿÿÿ \ K0 G I & ÿÿÿÿ ] L0 G I ÿÿÿÿ ^ M0 G I ÿÿÿÿ _ N0 G I ! ÿÿÿÿ ` O0 G I " ÿÿÿÿ a P0 G I # ÿÿÿÿ b Q0 G H ' $
ÿÿÿÿ c R0 G H ' %
ÿÿÿÿ d S0 G J & ÿÿÿÿ e T0 G J ' ÿÿÿÿ % f U‹ ÿÿÿÿ ( ÿÿ g V0 U U ( ) ÿÿÿÿ h W0 U U * ÿÿÿÿ i X0 U U + ÿÿÿÿ j Y0 U W , ÿÿÿÿ k Z0 U W - ÿÿÿÿ l [0 U W . ÿÿÿÿ m \0 U W / ÿÿÿÿ n ]0 U W 0 ÿÿÿÿ o ^0 U W 1 ÿÿÿÿ p _0 U V ) 6
ÿÿÿÿ q a0 U V ) 7
ÿÿÿÿ r b0 U X 4
ÿÿÿÿ s c0 U X 5
ÿÿÿÿ t d‹ ÿÿÿÿ ( ÿÿ u e0 d d ) ÿÿ h v f0 d d * ÿÿÿÿ w g0 d d 2 ÿÿÿÿ x h0 d f , ÿÿÿÿ y i0 d f 3 ÿÿÿÿ z j0 d f 8 ÿÿÿÿ { k0 d f 9 ÿÿÿÿ | m0 d f : ÿÿÿÿ } n0 d e * 6
